Repository navigation
feat(xtask): require every source file to have an entry in docs/architecture.md - #949
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The link scanner counts paths inside HTML comments and code as documented references, allowing the coverage gate to pass when a source file is absent from the rendered module map.
1 open issue
What changed in this PR
Adds a contributor-facing check requiring production Rust source files to appear in the architecture module map, complementing existing link-resolution checks.
Changes:
- Adds
cargo xtask check-architecture-docwith test-helper exemptions, stale-exemption detection, and unit tests. - Wires the check into commit/push hooks and CI, with a contract test protecting that wiring.
- Updates contributor guidance and the PR checklist to explain the requirement and its limits.
| File | Description |
|---|---|
xtask/src/workflow_contract.rs |
Tests hook stages, CI wiring, and path-filter coverage. |
xtask/src/main.rs |
Registers and dispatches the new command. |
xtask/src/architecture_doc.rs |
Implements source citation checks, exemptions, and tests. |
docs/testing.md |
Documents running the check. |
docs/architecture.md |
Explains citation enforcement and exemptions. |
CONTRIBUTING.md |
Adds contributor requirements and hook guidance. |
AGENTS.md |
Adds architecture-map maintenance rules. |
.pre-commit-config.yaml |
Runs the check at commit and push. |
.github/workflows/ci.yml |
Adds the CI step and architecture-doc path trigger. |
.github/pull_request_template.md |
Adds a module-map maintenance checklist item. |
Review effort: Balanced
There was a problem hiding this comment.
🟡 Changes recommended
The citation scanner accepts malformed Markdown links but rejects valid entity-encoded angle-delimited destinations, allowing broken citations to pass while valid entries fail the hook and CI.
2 open issues
1 resolved since last review
Review effort: Balanced
juhovainio
left a comment
There was a problem hiding this comment.
No blocking issues. The check, hook and CI wiring look right, and the docs are updated together. A few non-blocking points, left as inline comments:
- Malformed links (unclosed
(, missing[, escaped[) are accepted as citations, so a broken entry keeps the gate green. This matches the open Copilot comment. - Angle-bracket destinations like
[x](<../a.rs>)are rejected, so a valid reformatted entry fails the hook and CI (fails closed). Also matches an open Copilot comment. - The failure message points authors at EXEMPT, which AGENTS.md §6 and CONTRIBUTING say not to do.
- "EXEMPT can only shrink" is stated in several places but nothing enforces it.
Approving on a diff-only read; I didn't build or run it, so CI is the execution evidence.
| let mut rest = doc.as_str(); | ||
| while let Some(at) = rest.find("](") { | ||
| rest = &rest[at + 2..]; | ||
| let end = rest.find([')', ' ', '\n']).unwrap_or(rest.len()); |
There was a problem hiding this comment.
The scan takes any ](…next )/space/newline as a destination without checking for the closing ) or the opening [. So [cli](../apps/rocm/src/cli.rs (unclosed), cli](../x.rs) and an escaped \[x](...) all still count as citations, and a mangled entry keeps the gate green even though it no longer renders as a link. Worth validating the full [text](dest) shape and adding regression cases for missing delimiters and escapes.
There was a problem hiding this comment.
Fixed in e8c602c. The scan now accepts only a complete inline link: an unescaped [ on the same line, a balanced-parenthesis or <...> destination, an optional title and the closing ). A link missing its ) or [, an escaped \[, and a stray [ on an earlier line no longer count, and breaking_the_only_entry_leaves_the_file_uncited covers each shape at the check level. Each rule has a test that fails when the rule is disabled.
| #[allow(clippy::case_sensitive_file_extension_comparisons)] // Rust sources are always lowercase `.rs` | ||
| fn resolve_link(target: &str) -> Option<String> { | ||
| let target = target.split('#').next()?; | ||
| if target.contains("://") || !target.ends_with(".rs") { |
There was a problem hiding this comment.
[cli](<../apps/rocm/src/cli.rs>) is valid CommonMark, but the target then ends with >, so ends_with(".rs") fails and the hook/CI reject a correctly rendered entry. Stripping the optional <...> delimiters before resolving (plus a test) would fix it.
There was a problem hiding this comment.
Fixed in e8c602c. A <...> destination has its delimiters removed before the path is resolved, so [cli](<../apps/rocm/src/cli.rs>) and its #L10 and titled variants count as citations, and an unterminated < is not a link. an_angle_bracketed_destination_is_a_citation covers it and fails when the angle-bracket branch is disabled.
| for path in &in_tree { | ||
| if !cited.contains(*path) && !exempt.contains(path) && !is_test_helper(path) { | ||
| violations.push(format!( | ||
| "`{path}` is not cited in {DOC}: add an entry for it to the module map, as a \ |
There was a problem hiding this comment.
This message tells the author to add the file to EXEMPT when it "deliberately has no entry", but AGENTS.md §6 and CONTRIBUTING say not to add to EXEMPT to make the check pass. I'd have the message say only to add an entry, and keep growing EXEMPT a reviewed exception.
There was a problem hiding this comment.
Fixed in e3494f2. The message for an uncited file now only asks for an entry in the module map and no longer mentions EXEMPT, so it agrees with AGENTS.md and CONTRIBUTING. the_failure_message_for_an_uncited_file_only_asks_for_an_entry pins it, and fails if the hint comes back.
|
|
||
| /// Production files that have no entry in `docs/architecture.md` yet: everything | ||
| /// that was uncited when this check was added, mostly the dashboard crates. | ||
| /// Do not add to this list to make the check pass: document the file in the doc |
There was a problem hiding this comment.
"can only shrink" (here and in AGENTS.md/CONTRIBUTING/architecture.md) isn't enforced: check() flags stale entries, but adding an uncited file to EXEMPT passes. Either reword (e.g. "grows only via a reviewed edit") or add a ratchet.
There was a problem hiding this comment.
Fixed in e3494f2, with both of your options. I added a ratchet: EXEMPT_CEILING caps the list at its current size, enforced by check-architecture-doc itself and by a unit test, so growing the list means raising that constant too, a second visible line in the diff. It cannot stop a determined edit, so I also reworded the claim everywhere it was made (module docs, AGENTS.md, CONTRIBUTING) from "can only shrink" to "meant to shrink, with a capped size", and said what the cap does and does not guarantee.
There was a problem hiding this comment.
🟡 Changes recommended
The citation parser incorrectly accepts images and invalid nested links while mishandling escaped backticks, allowing missing citations to pass and valid citations to fail.
3 open issues
2 resolved since last review
Review effort: Balanced
| out.push(' '); | ||
| continue; | ||
| } | ||
| if rest.starts_with('`') { |
There was a problem hiding this comment.
Fixed in e3494f2. A backslash-escaped backtick or < now opens nothing, and both characters are kept so the link scan still sees the escape. Your input, Use \ for a backtick; cli.rs, now cites the file. an_escaped_backtick_does_not_open_a_code_spancovers it, including an escaped backslash before a real backtick and an escaped<!--`, and fails when escape handling is disabled.
| } | ||
| match bytes[at] { | ||
| b'\n' => open = 0, | ||
| b'[' => open += 1, |
There was a problem hiding this comment.
Fixed in e3494f2. Openers are tracked as image or link, and an image destination is no longer a citation, so  leaves the file uncited. A link whose text contains an image still counts, and an escaped \! is not an image. I reversed the old assertion at that line and added an_image_is_not_a_citation, an_escaped_exclamation_mark_does_not_make_an_image and an_image_inside_a_links_text_leaves_the_link_valid.
| found.push(destination); | ||
| at += 2 + length; | ||
| continue; |
There was a problem hiding this comment.
Fixed in e3494f2. When an inner link forms, the outer link openers are deactivated, as links do not nest, so [cli [details](../README.md)](../apps/rocm/src/cli.rs) no longer cites cli.rs. Image openers are left alone, and plain brackets that do not form a link do not deactivate anything, so [a [b] c](path) still works. a_link_containing_a_link_cites_only_the_inner_one covers it, including a later link on the same line, and is distinct from the plain-brackets case.
…to be in the module map docs/architecture.md says it is updated in the same PR as the code it documents, but nothing enforced it. The lychee link check only confirms that links already in the doc resolve, so a new module nobody wrote an entry for passed silently. `cargo xtask check-architecture-doc` starts from the tree instead: every tracked .rs file under apps/*/src, crates/*/src and engines/*/src must be linked from the doc, listed in EXEMPT, or be a test-only helper matched by file stem. EXEMPT holds the 78 files uncited today and, like ALLOWLIST in check-crate-edges, is checked both ways, so it can only shrink. The architecture-doc prek hook runs it at pre-commit and pre-push, over the whole tree on every run, so a commit made with --no-verify is still caught at push. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…ith a contract test The step is gated on the rust path filter like the other xtask checks in that job. The filter now also lists docs/architecture.md, because deleting or rewording an entry changes the answer though no .rs file moved. architecture_doc_check_runs_in_hooks_and_ci reads .pre-commit-config.yaml and ci.yml and fails if the hook loses a stage, gains a file filter or stops running on every commit, or if the CI step or the path-filter entry goes missing. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…sting and agent guides architecture.md and CONTRIBUTING.md previously said only that file links in the doc are checked for resolution. They now say the reverse is checked too: a production source file with no entry fails check-architecture-doc, and what the check does not cover (whether an entry's prose is still true). AGENTS.md section 5 and 6 and the PR template ask for the entry in the same change as the file, and say not to add a file to EXEMPT to make the check pass. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…module map The citation scan looked for a raw `](` in docs/architecture.md, so a link inside an HTML comment, a fenced block or an inline code span still counted. Commenting out the only entry for a file kept the check green although the rendered module map no longer documented it. The doc is now reduced to its rendered link text first: HTML comments, fenced code blocks and code spans are removed in one left-to-right pass, so a backtick inside a comment and a comment marker inside a code span keep their usual precedence. Where it cannot tell, it hides a link, which can only make the check fail. Indented code blocks are not recognised. New tests cover each construct, the precedence cases, CRLF input, and the commented-out-entry scenario at the check level. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…odule map cites it The module map gained an entry for crates/rocm-dash-daemon/src/registry.rs on main, so the stale-entry check rightly rejected its EXEMPT line after the merge. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The citation scan took any `](` as a link, which both over- and under-counted. A destination in angle brackets, `[cli](<../apps/rocm/src/cli.rs>)`, was rejected because the `<` and `>` stayed in the path, so reformatting an existing entry failed the hook and CI. A link missing its `)` or its `[`, or with an escaped bracket, was counted as a citation although the rendered page shows plain text, so breaking the only entry for a file kept the gate green. Links are now parsed as `[text](destination "title")`: an unescaped `[` on the same line, a balanced-parenthesis or `<...>` destination, an optional title and the closing `)`. A link that is not complete is not a citation. A link whose text spans lines is not recognised, which can only make the check fail. New tests cover angle-bracket destinations, each missing delimiter, escaped brackets and parentheses, a stray `[` on an earlier line, nested brackets, parentheses in a path, and several links on one line. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…e images and nested links Review feedback on the module-map check. The failure message for an uncited file told authors they could add it to EXEMPT, which AGENTS.md and CONTRIBUTING.md say not to do; it now only asks for an entry. "EXEMPT can only shrink" was not enforced, so EXEMPT_CEILING now caps the list's size in the command and in a test: growing the list means raising that constant too, a visible reviewed edit. The docs say "meant to shrink" instead of promising what the code did not guarantee. The link scanner also treated three shapes as citations or non-citations wrongly. An image, , renders as an image and no longer counts, while a link whose text contains an image still does. The outer brackets of a link that contains another link no longer count, since links do not nest. A backslash-escaped backtick no longer opens a code span, which had swallowed the `[` of a real link and reported its file as uncited. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
f0fe0d4 to
e3494f2
Compare
tomastola
left a comment
There was a problem hiding this comment.
Thanks for e8c602c: it fixes both open Copilot threads. Broken entries (a missing [ or ), an escaped \[) no longer count as citations (line 303), and [x](<path>) is now accepted (line 165). e3494f2's EXEMPT_CEILING turns "the list can only shrink" into something the code enforces, and its image, nested-link and escaped-backtick handling closes the remaining parser gaps I'd have raised. I ran cargo test -p xtask architecture_doc (all pass) plus a probe through cited_paths confirming each of the e8c602c cases on the pre-rebase head f0fe0d4a, and cargo xtask check-architecture-doc passed there; on e3494f2 I read the diff but did not re-run them. Nothing here blocks; the notes below are for you to weigh.
1. Remaining link forms (note only). Reference-style links ([cli][c] plus [c]: ../apps/rocm/src/cli.rs), …/cli.rs?plain=1 and root-relative /apps/rocm/src/cli.rs render as working links but still aren't counted, so they fail the check. The docs now say to use an inline [text](path) link, which covers it; just flagging that the failure message will tell someone to add an entry that is already there if they use one of these forms.
2. Pre-push reads the working tree, not the commits being pushed. The module comment (architecture_doc.rs:23-24) says the check "behaves the same in CI, in the pre-commit hook and in the pre-push hook", and the PR body says pre-push catches a commit made with --no-verify. Pre-commit is fine, because prek stashes unstaged changes first. At pre-push, though, git ls-files and read_to_string(docs/architecture.md) read the current index and working tree. Take a commit that adds foo.rs with no entry, pushed while the doc entry is staged or edited but not committed: pre-push passes and CI fails. CI is the real gate, so this is just about wording. Either soften the claim, or have the pre-push path read git ls-tree/git show of the pushed ref.
3. Scope note. build.rs files at crate roots (apps/rocm/build.rs, crates/rocm-core/build.rs, crates/rocm-deps/build.rs) are production code but outside */src, so the check never looks at them. That's a reasonable boundary. Since the docs say "every production source file", it may be worth one clause saying what is out of scope (build.rs, tests/, examples/).
4. Nit. crates/rocm-engine-protocol/src/lib.rs is in EXEMPT, while AGENTS.md calls that crate a contract surface. It's probably the most useful entry to document first, which would also start shrinking the list.
…ent rocm-engine-protocol Review notes on the check. The check reads the index and the working tree. At pre-commit prek stashes unstaged changes first, so it matches what is being committed; at pre-push it reads the working tree, not the commits being pushed, so it only agrees with CI on a clean tree. The module comment, the hook comment and the contract test's doc no longer say pre-push always catches a commit made with --no-verify, and the module comment says CI is the gate. The docs now name what is out of scope (build.rs, tests/, examples/) and which link forms are not recognised (reference-style, a ?query suffix, root-relative paths). The failure message says so too, and a test holds that claim to what the parser does. crates/rocm-engine-protocol/src/lib.rs, a contract surface, now has an entry in docs/architecture.md and comes off EXEMPT, and EXEMPT_CEILING drops to 76. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
|
Thanks for the thorough read. All four notes are addressed in 6ba5a56 (pushed as part of 171c1e6, merged with the latest main).
|

Summary
docs/architecture.mdsays it is "updated in the same PR as the code it documents", but nothing enforced that. This addscargo xtask check-architecture-doc, which fails when a production source file has no entry in the module map, and runs it from theclippyCI job, a newarchitecture-docprek hook at pre-commit and pre-push, and a contract test that pins the wiring.How this differs from the lychee check
lychee checks one direction: every link already written in a markdown file resolves. It only sees what the doc already cites, so a new
foo.rsthat nobody mentions has no link to check and passes. This check starts from the source tree instead. Deleting or renaming a documented file is still caught by lychee (the link breaks); the new check adds the case lychee cannot see, a file with no entry.What it checks
Every tracked
.rsfile underapps/*/src,crates/*/srcandengines/*/srcmust be one of: linked fromdocs/architecture.mdas a relative markdown link that renders as a link (a path inside an HTML comment, a fenced code block or an inline code span does not count, so commenting out an entry cannot keep the gate green; neither does a malformed link, an image, or the outer brackets of a link that contains another link), listed inEXEMPT, or a test-only helper matched by whole file stem (test_support,test_env,proptests,*_proptests,*_props,*_properties). It reads the git index and the working tree, never a diff, so it gives the same answer in CI, at pre-commit and at pre-push.EXEMPTholds the 76 files still uncited, mostly in the dashboard crates (78 when the check was written; a change merged tomainsince then documented one of them, and the stale-entry rule correctly failed until its line was removed; this PR documentscrates/rocm-engine-protocol/src/lib.rs, a contract surface, and takes it off the list). It follows theALLOWLISTpattern incheck-crate-edgesand fails in both directions: a source file in neither the doc nor the list fails, and so does an entry that is now cited, no longer exists, or is redundant with the test-helper rule. The list is meant to shrink as files are documented. Nothing can stop a determined edit from adding to it, soEXEMPT_CEILINGcaps its size, enforced by the command itself and pinned by a test: growing the list means raising that constant too, a second, visible line in the diff for a reviewer to accept. The failure message for an uncited file only asks for an entry; it does not mentionEXEMPT.Wiring
.pre-commit-config.yaml:architecture-dochook,stages: [pre-commit, pre-push],always_run: true,pass_filenames: false, in thelocal-toolsgroup like the other xtask-backed hooks. It has no file filter because the answer depends on the whole tree and a delete-only commit has no changed files to match. The check reads the git index and the working tree, so at pre-commit (where prek stashes unstaged changes first) it matches what is being committed. At pre-push it reads the working tree rather than the pushed commits, so with a clean tree it also catches a commit made with--no-verify, but with staged or unstaged edits it can pass where CI fails. CI is the gate and the hooks are feedback; the module comment and hook comment say so..github/workflows/ci.yml: a step in theclippyjob next tocheck-crate-edges, gated on therustfilter. Therustfilter now also listsdocs/architecture.md, because deleting or rewording an entry changes the result though no.rsfile moved.architecture_doc_check_runs_in_hooks_and_ciinxtask/src/workflow_contract.rsreads both files and fails if the hook loses a stage, gains a file filter or stops running on every commit, or if the CI step or the path-filter entry goes missing.docs/architecture.md,CONTRIBUTING.md,docs/testing.md,AGENTS.md(sections 5 and 6) and the PR template. They previously said only that the doc's links are checked for resolution.What it does not cover
Whether an entry's prose still describes its file, and functions that move between two files that are both already cited. The docs say so rather than implying otherwise.
Verification
xtask/src/architecture_doc.rsplus the contract test. Run on the pushed tree, for the affected crate only:cargo test -p xtask --no-fail-fast(610 passed),cargo clippy --locked -p xtask --all-targets -- -D warnings,cargo fmt --all --check,cargo xtask lychee, and the leak scan against the merge base (clean).exempt_entry_that_is_now_cited_is_stale, letting..climb out of the repo root failsonly_in_repo_rust_links_count_as_citations, droppingpre-pushfrom the hook fails the contract test, and removingdocs/architecture.mdfrom therustfilter fails the contract test. For the link scanner, disabling comment stripping fails 3 tests (including the commented-out-entry scenario), disabling fence stripping failsa_link_in_a_fenced_code_block_is_not_a_citation, and disabling code-span stripping fails 2 tests.[text](destination "title"): an unescaped[on the same line, a balanced-parenthesis or<...>destination, an optional title and the closing). A link missing its[or), or with an escaped bracket, is plain text when rendered and does not count; an angle-bracketed destination does count. An image,, does not count, while a link whose text contains an image does; the outer brackets of a link that contains another link do not count, since links do not nest; a backslash-escaped backtick or<opens no code span or comment. Link text spanning lines is not recognised, which can only make the check fail. Mutation checks (the later rules too: ignoring escapes before code markers failsan_escaped_backtick_does_not_open_a_code_span, never treating an opener as an image fails 2 tests, not deactivating outer link openers failsa_link_containing_a_link_cites_only_the_inner_one, loweringEXEMPT_CEILINGfails the ceiling test, and putting theEXEMPThint back in the message fails its test): accepting a link without its)failsa_link_missing_its_closing_parenthesis_is_not_a_citation, dropping angle-bracket support fails 2 tests, ignoring backslash escapes fails 2 tests, and no longer resetting open brackets at a newline failsa_link_missing_its_opening_bracket_is_not_a_citation.engines/vllm/src/,cargo xtask check-architecture-docexits 1 and names the file; with it removed the command exits 0.xtask) was checked. CI is authoritative for the rest.No Gherkin scenario: this is internal CI and hook plumbing with no user-observable
rocmCLI behaviour (no command output, exit codes, files or engine selection change), and the xtask command is a contributor tool. The message the check prints names a real action, and the end-to-end run above exercises the failing path.Rebased onto
origin/mainonce and force-pushed with a lease (the approval on the PR stood after the push); later main commits were merged in with plain pushes. The check passes on the pushed tree. Out of scope for the check, and now said so in the docs:build.rsfiles and thetests/andexamples/trees. Link forms the check does not recognise, and the failure message says so: reference-style links, a?querysuffix and root-relative paths. The pre-push hook was skipped with--no-verifyfor the pushes: the first run failed on an unrelatedapps/rocmtest that passes alone, and CI is the authoritative gate for the workspace suite.